Developer CD Series 1995…tember: Reference Library/Dev.CD Sep 95 RL/Dev.CD Sep 95 RL.toast/mac/Utilities/Apple DocViewer™ v1.1.1/DocViewer Apple Events Info/DocViewer Lookup TechNote/DocViewer Lookup TechNote

Text File | 1994-09-26 | 17.1 KB | 35 lines | [ONLN/HLX2]

#004 New Apple Event Support in DocViewer 1.1.1

Introduction
Beginning with version 1.1.1, Apple DocViewer supports a special Apple event.  This Apple event is known as the "DocViewer Lookup" event.  With this event, it is possible to send a message to DocViewer requesting that it open a particular document and turn to a specific heading.  This DocViewer Tech Note describes the implementation of this event.  Please note that tech notes 1 - 3 do not address the Viewer portion of DocViewer and are only available to licensees of the Apple DocViewer Builder.
DocViewerLookup.h
Accompanying this Tech Note is a C header file for many of the constants and data structures  you will need when interacting programmatically with DocViewer.
Event Parameters
The Lookup event accepts three parameters.  These parameters are encapsulated into a single data structure for this version.  (We will parameterize them at the Apple event level for the next release.)  This data structure is the only parameter of the Apple event.  The structure is defined as:
typedef    struct {
    FSSpec    aDoc;            //    FSSpec for the Doc to open/search
    Str255    aPattern;    //    String in heading to find (length                                 // prefixed)
    short        accessLevel;//    find level
}SeekParamRec, *SeekParamRecPtr, **SeekParamRecHandle;
The first parameter is an FSSpec to the document you wish to open and perform the lookup in.  DocViewer will open this document if it isn't already open.  This document must be a DocViewer document (Creator: HLX2 Type:ONLN.)  If you pass a document that does not belong to DocViewer, it will return a kWrongFileType in the 'errn' parameter of the Apple event reply.
The second parameter is the heading you wish DocViewer to look for.  This is a simple Pascal-style string with a maximum length of 255 characters.  DocViewer uses this string as a pattern to match against the document's Table of Contents.  The comparison is accomplished without regard to case or diacritical marks. (e.g. FAT == fAt,  fåt = fat).  If the string you pass in isn't found in the document's Table of Contents, then DocViewer will return a kEntryNotFound error.
The third and final parameter is used to qualify the search pattern in the second parameter.  Once DocViewer has located the entry in the Table of Contents it will confirm that the entry is in the level of the TOC hierarchy specified in the accessLevel field.  DocViewer supports seven levels of hierarchy.  They are defined as follows:
#define        kFirstLevelHier            1
#define        kSecondLevelHier        2
#define        kThirdLevelHier            3
#define        kFourthLevelHier        4
#define        kFigureLevelHier        201
#define        kListLevelHier                202
#define        kTableLevelHier            203
An eighth constant has been defined that will allow the entry to be found at any level in the hierarchy.  In this case, if there are duplicate entries the first entry will be chosen.
#define        kAnyLevelHier                999
Each of these selectors is mutually exclusive, and they cannot be combined (or'd) together.
Sending The Event
Launch DocViewer with Document
The first step when sending the lookup event is to see if DocViewer is currently running.  This can be accomplished with the Process manager GetProcessInfo routine.  If DocViewer is found in the list of currently running processes, you should check to see that the version of DocViewer is correct (1.1.1).  This can be done using the 'vers' resource with ID #1.
If DocViewer is not running, it is necessary to launch the application with the target document.  If DocViewer is launched without reference to the target document, it will present its default SFGetFile dialog, and you will not be able to message the application until the dialog is dismissed.  For information on launching an application with a document see "LaunchwithDoc" on the latest version of the Developer CD (Tool Chest Edition).
Again, when you launch the application, it is necessary to confirm that you are launching the correct version by checking the contents of the 'vers' ID #1 resource of the DocViewer application.
Send the Event
Once you have determined that DocViewer is running (or you've launched it) you can then send the event.  See listing 1 for an example of sending the 'seek' event.
Check for Errors
If DocViewer cannot find the entry requested, it will return an error in the reply of the Apple event.  See listing 1 for an example of how to determine these errors.
Listing 1 - Sending the 'seek' Apple event
//OpenDoc
// This routine takes a pointer to a SeekParamRec
// and sends it to DocViewer.  This routine assumes
// that you've already checked to see if DocViewer is running
// I removed most the error checking where it was obvious
// to improve readability.
OSErr OpenDoc(SeekParamRec *qData)
{
    OSErr                        err = noErr;
    AppleEvent        myEvent, reply;
    AEDesc                    myAddress;
    long                        appSig = kDocViewerAppSig;
    long                        replyError = noErr;
    Size                        actualSize;
    DescType                gotType;

    err = AECreateDesc(    typeApplSignature,(Ptr)&appSig,
                        sizeof(appSig),&myAddress);

    err = AECreateAppleEvent(kDocViewerEventClass, kSeekEventID,
                                                                        &myAddress, kAutoGenerateReturnID,
                                                                        kAnyTransactionID, &myEvent );

    err = AEPutParamPtr( &myEvent, keySeekParam, typeWildCard,                                                             (Ptr)qData, sizeof(SeekParamRec) );
    err = AESend( &myEvent, &reply, kAEWaitReply,                                                 kAENormalPriority, kAEDefaultTimeout,
                                        nil, nil );
   // Check to see if you got an error
    err = AEGetParamPtr( &reply, keyErrorNumber, typeLongInteger,                                                             &gotType, (Ptr)&replyError,
                                                          sizeof(long), &actualSize);
    // Special case on AEDescNotFound because we'll get an error
    // if there is no error in the reply.
    if ((err != noErr) && (err != errAEDescNotFound))
    {
        return err;
    }
    // if there's an error from DocViewer return it.
    // otherwise return noErr.
    if (replyError != noErr)
            return replyError;
    else
            return noErr;
}
2dˇˇˇˇˇd°dWORDC
«

N~ëE åå@°ñ

,Palatino

.C
«C
«+≤ÉApple DocViewer
†ó°ñ


(É
…Technical Note†ó°ñ


(LÉ

*' Apple Computer, Inc., Developer Press†óê    häà™¸¸˛ˇ¸ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛ˇˇˇ˛?ˇˇ¯ˇ¯ˇ¯ˇ¯ˇ¯ˇ¯¯8ê    häà™
¸¸@Ä¿
¿
«·¿
Δ«
¿
«¡¿
¿
«ÅΔ¿
Δ!¿QΔ«…¿%¿‡¿ˇ¸˛ˇ˙˛%
įÄ8888ˇ8¯8

d




°dONLNd´~ø(∫~/#004 New Apple Event Support in DocViewer 1.1.1
°dONLNd2·ZÒ©(ÌZIntroduction
°dONLNd?˜~
æ+$
Beginning °dONLNdI˜æ

)@6with version 1.1.1, Apple DocViewer supports a special°dONLNdÄ
~
Ã(
~Apple event.  
°dONLNdé
Ã

)N3This Apple event is known as the "DocViewer Lookup"°dONLNd¬
~
!
Ã(
~=event.  With this event, it is possible to send a message to °dONLNdˇ

Ã
!
(

à    DocViewer°dONLNd
    
!~
/
L(
+~%requesting that it open a particular °dONLNd
.
!
L
/
)Œdocument and turn to a specific
°dONLNd
N
/~
=
ˇ(
9~@heading.  This DocViewer Tech Note describes the implementation °dONLNd
é
/
ˇ
=
(
9
ˇof°dONLNd
ë
=~
Kø(
G~
this event.  
°dONLNd
û
=ø
K
)A;Please note that tech notes 1 - 3 do not address the Viewer°dONLNd
⁄
K~
Y
—(
U~<portion of DocViewer and are only available to licensees of °dONLNd
K
—
Y
(
U
—    the Apple°dONLNd 
Y~
gÏ(
c~DocViewer Builder.
°dONLNd3
uZ
Ö‹(
ÅZDocViewerLookup.h
°dONLNdE
ã~
ô
fi+$>Accompanying this Tech Note is a C header file for many of the°dONLNdÑ
ô~
ß
“*=constants and data structures  you will need when interacting°dONLNd¬
ß~
µ
B* programmatically with DocViewer.
°dONLNd„
√Z
”À(
œZEvent Parameters
°dONLNdÙ
Ÿ~
Á
Ó+$@The Lookup event accepts three parameters.  These parameters are°dONLNd5
Á~
ı
Ô*Eencapsulated into a single data structure for this version.  (We will°dONLNd{
ı~*Gparameterize them at the Apple event level for the next release.)  This°dONLNd√~*Gdata structure is the only parameter of the Apple event.  The structure°dONLNd~≈*is defined as:,
Courier

°dONLNd%~1®*typedef°dONLNd"%¥1‰)6struct {°dONLNd,6¢BΔ(?¢FSSpec°dONLNd36ÿBˆ)6aDoc;°dONLNd;6
 B
,)H//°dONLNd>6
2B
¯)!FSSpec for the Doc to open/search°dONLNdaG¢SΔ(P¢Str255°dONLNdhGÿS
)6    aPattern;°dONLNdrG
 S
,)H//°dONLNduG
2S
˛)"String in heading to find (length °dONLNdüR
 ^
h([
 // prefixed)°dONLNd≠c¢o¿(l¢short°dONLNd¥cÿo
,)6accessLevel;//°dONLNd√c
2o
n)Z
find level°dONLNdœt~Ä
¬(}~6}SeekParamRec, *SeekParamRecPtr, **SeekParamRecHandle;
°dONLNdÖ~ì
*EThe first parameter is an FSSpec to the document you wish to open and°dONLNdLì~°*Eperform the lookup in.  DocViewer will open this document if it isn't°dONLNdí°~Ø
ÿ*9already open.  This document must be a DocViewer document°dONLNdÃØ~Ω
*(Creator: HLX2 Type:ONLN.)°dONLNdʨ
∫
!(∂

 °dONLNdÁØ
!Ω
Ó+% If you pass a document that does notˇXdˇˇˇˇˇd

d,Palatino
.°dONLNdH~V
L+~R&belong to DocViewer, it will return a ,
Courier

°dONLNd&I
LU
¶)ŒkWrongFileType 
°dONLNd5H
¶V
Í)Z
in the 'errn'°dONLNdCV~d
D(`~#parameter of the Apple event reply.°dONLNdij~x
*CThe second parameter is the heading you wish DocViewer to look for.°dONLNdÆx~Ü
Ë*AThis is a simple Pascal-style string with a maximum length of 255°dONLNdÜ~î*Icharacters.  DocViewer uses this string as a pattern to match against the°dONLNd
:î~¢
„*=document's Table of Contents.  The comparison is accomplished°dONLNd
x¢~∞
˝*Kwithout regard to case or diacritical marks. (e.g. FAT == fAt,  fåt = fat).°dONLNd
≈∞~æ
ÿ*@If the string you pass in isn't found in the document's Table of°dONLNdæ~Ã
]*'Contents, then DocViewer will return a 

°dONLNd-ø
]À
∑)flkEntryNotFound 
°dONLNd<æ
∑Ã
÷)Zerror.°dONLNdC“~‡
˘(‹~FThe third and final parameter is used to qualify the search pattern in°dONLNdä‡~Ó
Ù*Bthe second parameter.  Once DocViewer has located the entry in the°dONLNdÕÓ~¸
Û*GTable of Contents it will confirm that the entry is in the level of the°dONLNd¸~


)*TOC hierarchy specified in the 

°dONLNd4˝
)
    
k)´accessLevel
°dONLNd?¸
k


)B field.  DocViewer supports°dONLNd[

~

¨(
~8seven levels of hierarchy.  They are defined as follows:

°dONLNdî
~
*®*#define°dONLNdù
¥
*
)6kFirstLevelHier°dONLNdØ

2
*
8)~
1°dONLNd±
)~
5®(
2~#define°dONLNd∫
)¥
5
)6kSecondLevelHier°dONLNdÃ
)
2
5
8)~
2°dONLNdŒ
4~
@®(
=~#define°dONLNd◊
4¥
@
)6kThirdLevelHier°dONLNdÈ
4
2
@
8)~
3°dONLNdÎ
?~
K®(
H~#define°dONLNdÙ
?¥
K
)6kFourthLevelHier°dONLNd
?
2
K
8)~
4°dONLNd
J~
V®(
S~#define°dONLNd
J¥
V
)6kFigureLevelHier°dONLNd#
J
2
V
D)~201°dONLNd'
U~
a®(
^~#define°dONLNd0
U¥
a
)6kListLevelHier°dONLNdB
U
2
a
D)~202°dONLNdF
`~
l®(
i~#define°dONLNdO
`¥
l
)6kTableLevelHier°dONLNda
`
2
l
D)~203
°dONLNde
q~

Ô(
{~CAn eighth constant has been defined that will allow the entry to be°dONLNd©
~
ç
˝*Jfound at any level in the hierarchy.  In this case, if there are duplicate°dONLNdÙ
ç~
õ
G*'entries the first entry will be chosen.

°dONLNd
°~
≠®*#define°dONLNd%
°¥
≠
)6
kAnyLevelHier°dONLNd6
°
2
≠
D)~999
°dONLNd:
≤~
¿
‡(
º~AEach of these selectors is mutually exclusive, and they cannot be°dONLNd|
¿~
Œ
*combined (or'd) together.
°dONLNdñ
‹Z
Ï—(
ËZSending The Event
°dONLNd®
Ú~
D+$Launch DocViewer with Document°dONLNd«~
*FThe first step when sending the lookup event is to see if DocViewer is°dONLNd~"
*Ecurrently running.  This can be accomplished with the Process manager

°dONLNdT#~/“*GetProcessInfo
°dONLNdb"“0
˛)T9 routine.  If DocViewer is found in the list of currently°dONLNdú0~>
÷(:~>running processes, you should check to see that the version of°dONLNd€>~L*IDocViewer is correct (1.1.1).  This can be done using the 'vers' resource°dONLNd%L~Zº*with ID #1.°dONLNd2`~n
˙*FIf DocViewer is not running, it is necessary to launch the application°dONLNdyn~|*Ewith the target document.  If DocViewer is launched without reference°dONLNdø|~ä*Ito the target document, it will present its default SFGetFile dialog, and°dONLNd    ä~ò
‰*Cyou will not be able to message the application until the dialog is°dONLNdMò~¶
fl*>dismissed.  For information on launching an application with a°dONLNdå¶~¥*Cdocument see "LaunchwithDoc" on the latest version of the Developer°dONLNd–¥~¬
*CD (Tool Chest Edition).ˇ
ädˇˇˇˇˇd

d,Palatino
.°dONLNdH~V+~RGAgain, when you launch the application, it is necessary to confirm that°dONLNdHV~d
˚*Eyou are launching the correct version by checking the contents of the°dONLNdéd~r
ô*3'vers' ID #1 resource of the DocViewer application.°dONLNd¬x~Ü”*Send the Event°dONLNd—å~ö
Í*=Once you have determined that DocViewer is running (or you've°dONLNd
ö~®*Glaunched it) you can then send the event.  See listing 1 for an example°dONLNd
W®~∂
*of sending the 'seek' event.°dONLNd
tº~ ÿ*Check for Errors°dONLNd
Ö–~fi*HIf DocViewer cannot find the entry requested, it will return an error in°dONLNd
Œfi~Ï
Û*Ethe reply of the Apple event.  See listing 1 for an example of how to°dONLNdÏ~˙ˇ*determine these errors.
    °dONLNd,ˇ~

**Listing 1 - Sending the 'seek' Apple event,
Courier

°dONLNdW
~
¥*    //OpenDoc°dONLNda
~
"
§*1// This routine takes a pointer to a SeekParamRec°dONLNdì
!~
-
∞*3// and sends it to DocViewer.  This routine assumes°dONLNd«
,~
8
Ï*=// that you've already checked to see if DocViewer is running°dONLNd
7~
C
‘*9// I removed most the error checking where it was obvious°dONLNd?
B~
N
*// to improve readability.°dONLNdZ
M~
Y
J*"OSErr OpenDoc(SeekParamRec *qData)°dONLNd}
X~
dÑ*
{°dONLNdÄ
cê
oÆ+OSErr°dONLNdã
c·
o
))Qerr = noErr;°dONLNdô
nê
zÃ(
wê
AppleEvent°dONLNd•
n·
z
;)QmyEvent, reply;°dONLNd∂
yê
Ö¥(
ÇêAEDesc°dONLNd¡
y·
Ö
)Q
myAddress;°dONLNdÕ
Ñê
ê®(
çêlong°dONLNd◊
Ñ·
ê
})QappSig = kDocViewerAppSig;°dONLNdÛ
èê
õ®(
òêlong°dONLNd˝
è·
õ
S)QreplyError = noErr;°dONLNd
öê
¶®(
£êSize°dONLNd
ö·
¶
#)QactualSize;°dONLNd)
•ê
±¿(
ÆêDescType°dONLNd5
•·
±
)QgotType;°dONLNdA
ªê
«
(
ƒêerr = AECreateDesc(°dONLNdU
ª

«
»)~typeApplSignature,(Ptr)&appSig,°dONLNd{
ΔΩ
“
_(
œΩsizeof(appSig),&myAddress);°dONLNdö
‹ê
Ë
¯(
Âê<err = AECreateAppleEvent(kDocViewerEventClass, kSeekEventID,°dONLNdÍ
Á
)
Û
ı+ô"&myAddress, kAutoGenerateReturnID,°dONLNd 
Ú
)
˛
›*kAnyTransactionID, &myEvent );°dONLNdHê
Ú(ê;err = AEPutParamPtr( &myEvent, keySeekParam, typeWildCard, °dONLNdí

‡+~#(Ptr)qData, sizeof(SeekParamRec) );°dONLNd∑)ê5
§(2ê.err = AESend( &myEvent, &reply, kAEWaitReply, °dONLNdÒ4·@
ø+Q%kAENormalPriority, kAEDefaultTimeout,°dONLNd"?·K
#*nil, nil );°dONLNd.U~a
b(^~&   // Check to see if you got an error°dONLNdV`êl+>err = AEGetParamPtr( &reply, keyErrorNumber, typeLongInteger, °dONLNd£k
w
∞+~&gotType, (Ptr)&replyError,°dONLNd≈vΩÇ…(Ω  °dONLNdœv
Ç
∞)Qsizeof(long), &actualSize);°dONLNdÏÅêç
¯(äê<// Special case on AEDescNotFound because we'll get an error°dONLNd*åêò
n*%// if there is no error in the reply.°dONLNdQóê£
∂*1if ((err != noErr) && (err != errAEDescNotFound))°dONLNdÑ¢êÆñ*
{°dONLNdà≠ôπ€+    return err;°dONLNdï∏êƒñ(¡ê
}°dONLNdò√êœ
∞*0// if there's an error from DocViewer return it.ˇ
Rdˇˇˇˇˇd

d,
Courier

.°dONLNdHêT
,+êQ// otherwise return noErr.°dONLNdSê_
 *if (replyError != noErr)°dONLNd8^¢j
+return replyError;°dONLNdLiêu®(rêelse°dONLNdTt¢Ä+
return noErr;°dONLNdb~ãÑ(à~
}ˇ